home *** CD-ROM | disk | FTP | other *** search
/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / TOOLS / BTRWATCH.ZIP / BTRWATCH.DOC < prev    next >
Encoding:
Text File  |  1991-09-15  |  24.5 KB  |  568 lines
  1.  
  2.  
  3.                                        BTR WATCH
  4.  
  5.                            A memory resident Btrieve Debugger
  6.  
  7.                                       Version 1.0
  8.  
  9.  
  10.  
  11.                                     By David Smith
  12.                            (c) 1991 Informative Technologies
  13.                               1718 M Street NW, Suite 292
  14.                                 Washington, D.C. 20036
  15.                                  Voice (202) 675-4528
  16.                                   FAX (202) 675-4529
  17.                                  CompuServe 71311,2334
  18.  
  19.  
  20.     What is Btr Watch?
  21.  
  22.             Btrieve is Novell's record-manager system designed to aid PC
  23.         programmers in the development of applications. Btrieve handles
  24.         all of the tasks associated with managing indexed records. Btrieve
  25.         is loaded as a TSR and applications make calls to Btrieve to access
  26.         indexed files.
  27.             Btr Watch is a memory resident Btrieve debugger. Btr Watch can
  28.         trace all Btrieve file accesses and log them to an ASCII file.
  29.         Btr Watch is loaded after Btrieve, but before the Btrieve application
  30.         program. Btr Watch can be used with any DOS application that uses
  31.         Btrieve.
  32.             Btr Watch is a set of two programs. The first program is a TSR
  33.         that loads into memory between Btrieve and the application program.
  34.         This program is BTRWATCH.EXE. This program intercepts Btrieve calls
  35.         and logs them to a file. The second part of Btr Watch is a program to
  36.         view the log file and to set the options of Btr Watch. This program
  37.         is not a TSR and is called WATCHBTR.EXE.
  38.  
  39.         Some of the features and uses of Btr Watch:
  40.  
  41.             o   Btr Watch helps in debugging applications. Load Btr Watch
  42.                 to make sure the correct sequence of Btrieve calls occur.
  43.                 Test applications by tracing Btrieve file operations.
  44.  
  45.             o   Btr Watch can log all Btrieve file accesses or just when
  46.                 certain status codes occur.
  47.  
  48.             o   Btr Watch can show all of the Btrieve file operations
  49.                 that affect a file. Btr Watch can be loaded at all
  50.                 times and will only log file operations when certain
  51.                 status codes occur. Btr Watch stores in memory a list
  52.                 of the last 100 file operations. When a designated
  53.                 status code occurs, Btr Watch will log up to 100
  54.                 Btrieve operations that happened just before the
  55.                 designated status code.
  56.  
  57.             o   Btr Watch works independently of the application.
  58.  
  59.             o   Btr Watch works with BTRIEVE.EXE or BREQUEST.EXE and
  60.                 is network compatible. Btr Watch can trace file
  61.                 accesses from multiple stations.
  62.  
  63.             o   Btr Watch catches files that have been opened multiple
  64.                 times without closing them or attempts to access files
  65.                 that are not open.
  66.  
  67.             o   If one of 10 different status codes occur, Btr Watch
  68.                 can automatically retry an operation. The number of
  69.                 retries and the delays between them is configurable.
  70.  
  71.             o   Btr Watch can log how long each Btrieve access takes.
  72.  
  73.             o   Btr Watch logs the date and time a Btrieve operation
  74.                 occurs. This lets you know exactly when file
  75.                 operations occur.
  76.  
  77.             o   Btr Watch can make a beep signal whenever a 'BAD' status
  78.                 code occurs so an operator can be alerted to take action
  79.                 immediately.
  80.  
  81.     QUICK START
  82.  
  83.         Here's how to use Btr Watch:
  84.  
  85.         Load Btrieve before Btr Watch is loaded. An example batch file is
  86.         provided that loads Btrieve 5.X and Btr Watch in the correct order.
  87.         This file is call "WATCH.BAT".  If you will be using BREQUEST.EXE
  88.         with Btr Watch, see the section on setting the 'file handle offset'
  89.         before you load BTRWATCH.EXE.
  90.             A log file will be created in the same directory as WATCHBTR.EXE.
  91.         Also, Btr Watch will create a configuration file called BTRWATCH.CFG
  92.         in the same directory as WATCHBTR.EXE when WATCHBTR.EXE is run for
  93.         the first time.  All program settings are stored in this file.
  94.  
  95.            ----------------------------------------------
  96.            Example: To load Btrieve 5.X and Btr Watch.
  97.  
  98.                BTRIEVE/M:64/P:4096/T:BTRIEVE.TRN
  99.                BTRWATCH
  100.            ----------------------------------------------
  101.  
  102.            OR
  103.  
  104.            ----------------------------------------------
  105.            Example: To load Btrieve 4.X and Btr Watch.
  106.  
  107.                BTRIEVE/P:4096/T:BTRIEVE.TRN
  108.                BTRWATCH
  109.            ----------------------------------------------
  110.  
  111.            OR
  112.  
  113.            ----------------------------------------------
  114.            Example: To load Brequest and Btr Watch.
  115.  
  116.                BREQUEST/D:54000
  117.                BTRWATCH
  118.            ----------------------------------------------
  119.  
  120.                Load a Btrieve application and use it normally. Every time
  121.            the application accesses a Btrieve file, an entry is placed in
  122.            a file called BTRWATCH.LOG. The application will run slower
  123.            because of the additional time needed to log the Btrieve
  124.            information.
  125.                Next, exit out of the application and return to the DOS
  126.            prompt. Run the program called "WATCHBTR.EXE". This program
  127.            will allow you to view the log file.  Select 'V' from the
  128.            main menu to display the log file. All Btrieve operations
  129.            will be listed in the file.
  130.  
  131.     BASIC OPTIONS
  132.  
  133.          This menu selection allows you to set various options for Btr Watch.
  134.  
  135.          Log all Btrieve accesses
  136.  
  137.              If this option is set to YES, all Btrieve file
  138.              accesses are logged. If this option is set to NO,
  139.              file access are only logged only if one of the status
  140.              codes from the status code list occurs.
  141.  
  142.          Beep for all accesses
  143.  
  144.              If this option is set to YES, a beep will sound for
  145.              every Btrieve operation. If this option is set to NO,
  146.              beeps will not sound for every Btrieve operation.
  147.  
  148.          Beep for status code list
  149.  
  150.              If this option is set to YES, Btr Watch will beep
  151.              when one of the status codes from the status code list
  152.              occurs. If this option is NO, Btr Watch will not
  153.              beep when a status code from the status code list
  154.              occurs.
  155.  
  156.          Log the time
  157.  
  158.              If this option is set to YES, the time will be
  159.              logged with each log entry. If this option is NO,
  160.              the time will not be logged.
  161.  
  162.          Log the date
  163.  
  164.              If this option is set to YES, the date will be
  165.              logged with each log entry. If this option
  166.              is 'NO', the date will not be logged.
  167.  
  168.          Log file name
  169.  
  170.              This is the name of the file Btr Watch will log the
  171.              Btrieve operations. If several stations are
  172.              logging to this file, make sure you put the full
  173.              file path to be sure all stations are using the
  174.              same file.
  175.  
  176.          Beep tone
  177.  
  178.              This is the hertz frequency of the beep sound made by
  179.              Btr Watch. The best values for this are between
  180.              1000 and 4000.
  181.  
  182.          Beep duration
  183.  
  184.              This is the length of the beep sound Btr Watch makes
  185.              in milliseconds.
  186.  
  187.     ADVANCED OPTIONS
  188.  
  189.          This selection allows you to set the advanced options for Btr Watch.
  190.  
  191.          Log length
  192.  
  193.              If this option is set to YES, the length of time a
  194.              Btrieve call lasts is logged. If this option is NO,
  195.              the time is not logged. The duration of the calls are
  196.              recorded in clock ticks. Each tick is 1/18 of a
  197.              second or about 55 milliseconds.
  198.  
  199.          Check for open
  200.  
  201.              If this option is set to YES, Btr Watch logs a
  202.              message if files were open when a RESET or STOP
  203.              operation occurs. If this option is NO, a message
  204.              is not logged.
  205.  
  206.          Ignore stop
  207.  
  208.              If this option is set to YES, Btr Watch does not allow an
  209.              application to unload Btr Watch from memory when it executes
  210.              a (25) STOP command. The Stop Command is also not passed to
  211.              Btrieve. The only way to unload Btr Watch and Btrieve from
  212.              your application when this option is set to YES is to set the
  213.              key number parameter to -1 when the STOP command is executed.
  214.              You are still able to unload Btr Watch and Btrieve with the
  215.              'Unload Btr Watch' menu option. If this option is set to NO
  216.              both Btr Watch and Btrieve are unloaded when the application
  217.              sends the (25) STOP command.
  218.  
  219.          Check for multiple opens
  220.  
  221.              If this option is set to YES, Btr Watch logs a message to the
  222.              log file when a file gets opened more than once at a time.
  223.              If this option is NO, a message is not logged.
  224.  
  225.          Log the station name
  226.  
  227.              If this option is set to YES, Btr Watch logs the station name.
  228.              If this option is NO, the station name is not logged.
  229.  
  230.          Station name
  231.  
  232.              This is a string describing the station where Btr Watch
  233.              is load. If you are using Btr Watch on more than
  234.              one station at a time, create different .CFG files for
  235.              each station. The path and name of the log file should
  236.              be the same for each of the different .CFG files. Each
  237.              station name should be different. Entering a different
  238.              name for each station allows you to follow the Btrieve
  239.              accesses from several stations.
  240.  
  241.          File handle offset
  242.  
  243.              This is the offset into the position block Btrieve is
  244.              supplied for each call. At this offset is a file
  245.              handle (integer) that is used by Btrieve and Btr Watch.
  246.              The handle is used to tell the difference between
  247.              different Btrieve files that may be open at the same
  248.              time. BTRIEVE.EXE and BREQUEST.EXE have different
  249.              offsets. These offsets may also change in the future.
  250.  
  251.              Currently BTRIEVE.EXE uses 90 as the offset and
  252.              BREQUEST.EXE uses 126 as the offset.
  253.  
  254.     STATUS CODE LIST
  255.  
  256.          This is a list of status codes returned from Btrieve that Btr Watch
  257.          should monitor. If any of these status codes occur, Btr Watch can
  258.          be configured to beep and/or log up to 100 of the Btrieve operations
  259.          that occured before the specified status code. See the
  260.          'Basic Options' section to select how you want Btr Watch to react
  261.          to these status codes.
  262.  
  263.     RETRY OPTIONS
  264.  
  265.          Btrieve sometimes returns status codes indicating problems that can
  266.          be corrected by retrying the operation again. If an application
  267.          is trying to lock a record or file when the record or file is
  268.          locked, these status codes could be returned: (85) FILE IN USE and
  269.          (84) RECORD IN USE.  Sometimes (2) I/O ERROR is returned and when it
  270.          is retried, it is successful. If the error is still returned after
  271.          several tries, it may indicate a real error and retrying will not
  272.          help. There are possibly other status codes that can be resolved by
  273.          retrying them and you can add them to the default list. Btr Watch
  274.          makes a note in the log file whenever it retries an operation. Up
  275.          to 10 different status codes can be monitored and the operations
  276.          can be retried if these status codes occur. The delay between
  277.          retries and the number of retries can be configured.
  278.  
  279.          Retry status codes
  280.  
  281.              This is a list of Btrieve status codes. If any of these codes
  282.              are returned by Btrieve, Btr Watch will call Btrieve again using
  283.              the same parameters 'Retries' number of times with a delay
  284.              between each retries.
  285.  
  286.          Retries
  287.  
  288.              This is the number of times Btr Watch should call Btrieve when a
  289.              status code from the Retry Status Codes list is returned. If 5
  290.              is entered in this field, the operation will be retried 5 times.
  291.              If 0 is entered, the operation will not be retried.
  292.  
  293.          Delay between retries
  294.  
  295.              This is the amount of time to wait in between retries of the
  296.              call to Btrieve. This value is in milliseconds.
  297.              1000 = 1 Second.
  298.  
  299.     SAVE SETTINGS
  300.  
  301.          Selecting this option causes the program settings for Btr Watch to
  302.          be saved to the file BTRWATCH.CFG. The next time BTRWATCH.EXE is
  303.          run or WATCHBTR.EXE is run, the settings are read out of this file.
  304.          Btr Watch must be unloaded from memory and reloaded before the new
  305.          settings take effect. A configuration file can be specified on
  306.          the command line if you want to load or save to a file with a name
  307.          other than BTRWATCH.CFG. If a configuration file is not given,
  308.          BTRWATCH.CFG is used as the configuration file.
  309.  
  310.     VIEWING THE LOG FILE
  311.  
  312.          The log file can be displayed using program WATCHBTR.EXE. Select
  313.          'V' from the main menu to display the log file. If you receive an
  314.          error when you try to display the log file either, there is not
  315.          a log file or the path to the log file is not correct. There will
  316.          not be a log file until BTRWATCH.EXE is run for the first time.
  317.          The path and file name of the log file can be set on the basic
  318.          options screen. The log file can be deleted while you are viewing
  319.          it by pressing 'D'. The log file can also be printed by pressing
  320.          'P' while it is being displayed. For more information on the keys
  321.          available while viewing a log file, see the LOG VIEWING KEYS
  322.          section.
  323.  
  324.     LOG FILE FORMAT
  325.  
  326.          The log file is stored in ASCII format and can be viewed with any
  327.          text editor. The format of the log file is as follows:
  328.  
  329.          DATE TIME STATION LENGTH FILE KEY-NUMBER OPERATION RESULT
  330.  
  331.          For example:
  332.  
  333.          10 Aug 91  09:41:21  ==========[ BTRWATCH Loaded ]=========
  334.          10 Aug 91  09:41:35  0                0  Open
  335.          10 Aug 91  09:41:36  0  NWSPAPER.BTR  0  Get First
  336.          10 Aug 91  09:41:36  1  NWSPAPER.BTR  0  Get Next   (9) END OF FILE
  337.              │         │      │        │       │     │        │
  338.              │         │      │        │       │     │        └── Result
  339.              │         │      │        │       │     └─────────── Operation
  340.              │         │      │        │       └───────────────── Key Number
  341.              │         │      │        └───────────────────────── File
  342.              │         │      └────────────────────────────────── Length
  343.              │         └───────────────────────────────────────── Time
  344.              └─────────────────────────────────────────────────── Date
  345.  
  346.          Some of these fields may not be present in your log file depending
  347.          on the program options that are set.
  348.  
  349.     LOG FILE MESSAGES
  350.  
  351.          The following is a list of messages you may find in the log file.
  352.  
  353.          10 Aug 91 12:00:00 =========[ BTRWATCH Loaded   ]=========
  354.  
  355.              This message is logged whenever Btr Watch is loaded
  356.              into memory.
  357.  
  358.          10 Aug 91 12:00:00 =========[ BTRWATCH Unloaded ]=========
  359.  
  360.              This message is logged whenever Btr Watch is unloaded
  361.              from memory.
  362.  
  363.          Some Btrieve calls are missing before the next entry.
  364.  
  365.              Btr Watch's internal queue of Btrieve calls has overflowed
  366.              and some of the calls were removed from the queue and not
  367.              put in the log file.
  368.  
  369.          More than 100 files are open.
  370.  
  371.              Btr Watch keeps a list of all open files in memory. Btr Watch
  372.              can not keep track of more than 100 files open at once.
  373.  
  374.          File EXAMPLE1.BTR was still open when a 'RESET' occured.
  375.  
  376.              Btrieve was reset when a file was still open.
  377.  
  378.          File EXAMPLE2.BTR was still open when a 'STOP' occured.
  379.  
  380.              Btrieve was removed from memory when a file was still open.
  381.  
  382.          File DATABASE.BTR was already open.
  383.  
  384.              A Btrieve file was opened a second time without it first
  385.              being closed from the first time it was opened.
  386.  
  387.          Status Code = (85) FILE IN USE, Retrying operation 'Open' again...
  388.  
  389.              Btr Watch is retrying an operation after Btrieve returned a
  390.              status code from the retry list.
  391.  
  392.     UNLOADING BTR WATCH
  393.  
  394.          This menu option unloads Btr Watch and Btrieve from memory if they
  395.          are loaded. It also closes any open Btrieve files and aborts any
  396.          transactions.
  397.              When the 'Ignore Stop' option on the 'Advanced Options'
  398.          screen is set to 'YES', Btr Watch (TSR) passes the STOP command to
  399.          Btrieve only if the key value is set to -1. This allows WATCHBTR.EXE
  400.          to unload BTRWATCH.EXE (It sets the key value to -1.) but
  401.          Btr Watch (TSR) filters out STOP commands from applications.
  402.  
  403.     COMMAND LINE ARGUMENTS
  404.  
  405.         All command line arguments are optional.
  406.  
  407.         WATCHBTR -SWITCHES <CONFIG FILE>
  408.  
  409.         BTRWATCH <CONFIG FILE>
  410.  
  411.             SWITCHES
  412.  
  413.                 -b     Use BIOS for video writes. If your computer has
  414.                        trouble displaying some of the windows on your
  415.                        screen, use this switch. This assists with
  416.                        incompatibility in the display.
  417.  
  418.                 -m     Disables color. Runs the program in monochrome.
  419.  
  420.             CONFIG FILE
  421.  
  422.                  The file contains all of the program options used by
  423.                  WATCHBTR and BTRWATCH. A configuration file can be
  424.                  specified on the command line if you want to load or
  425.                  save to a file with a name other than BTRWATCH.CFG.
  426.                  If a configuration file is not given, BTRWATCH.CFG
  427.                  is used as the configuration file.
  428.  
  429.     LIST OF FILES
  430.  
  431.             BTRWATCH.EXE    TSR Btrieve Debugger
  432.             WATCHBTR.EXE    Configuration and Log File Viewer
  433.             WATCHBTR.HLP    Help file for WATCHBTR.EXE
  434.             WATCH.BAT       Batch file with example settings to load
  435.                             BTRIEVE.EXE and BTRWATCH.EXE.
  436.             SITELICE.DOC    Site license information.
  437.             REGISTER.DOC    Registration information and a registration form.
  438.             VENDOR.DOC      Disk vendor instructions.
  439.             SYSOP.DOC       BBS operator instructions
  440.             README.DOC      Installation instructions
  441.             BTRWATCH.DOC    Btr Watch Documentation
  442.             PRODUCTS.DOC    List of Informative Technologies' software.
  443.  
  444.     CONTEXT-SENSITIVE HELP
  445.  
  446.         Pressing F1 at any time displays a help screen that relates to the
  447.         current context of the program. Use the PgUp/PgDn keys to display
  448.         the different pages of help text on the screen. Use the arrow keys
  449.         to move between cross-referenced items on the help screen and press
  450.         [ENTER] to select another help item.
  451.  
  452.     NOTES
  453.         All software or service names mentioned are trademarks, servicemarks
  454.         or registered trademarks of their respective holders.
  455.  
  456.     TECHNICAL SUPPORT
  457.  
  458.         There are several ways to contact the author:
  459.  
  460.             1.  Send Email on CompuServe to David Smith  #71311,2334
  461.             2.  Send a FAX to (202) 675-4529
  462.             3.  Leave a message at the Programmers Corner BBS for
  463.                 David Smith #1082, BBS# (301) 596-1180
  464.             4.  Leave a voice mail message at (202) 675-4528 for David Smith.
  465.             5.  By mail to:
  466.                      David Smith
  467.                      Informative Technologies Corporation
  468.                      1718 M Street NW, Suite 292
  469.                      Washington, DC 20036
  470.  
  471.            Please include all relevant information regarding your
  472.            problem including:
  473.  
  474.            1 - A description of the event.
  475.            2 - The steps that consistently reproduce the event.
  476.            3 - Btrieve version number, type, and command line
  477.                parameters. (BTRIEVE, BREQUEST, NLM, VAP)
  478.            4 - Hardware information. (Machine Type, Video Adapter)
  479.            5 - Command line used to load Btr Watch.
  480.            6 - Btr Watch version number.
  481.  
  482.          Feel free to leave comments and suggestions to the
  483.          attention of David Smith.
  484.  
  485.          Voice mail messages will probably not be answered until the next
  486.          day. Email responses will usually be the fastest, with a response
  487.          by the end of the day. If you are outside of the United States and
  488.          you need pre or post registration support, please include your
  489.          Email address or fax number when you leave a voice mail message
  490.          or send a fax.
  491.  
  492.                               ┌─────────┐
  493.                         ┌─────┴───┐     │               (R)
  494.                       ──│         │o    │──────────────────
  495.                         │   ┌─────┴╨──┐ │  Association of
  496.                         │   │         │─┘  Shareware
  497.                         └───│    o    │    Professionals
  498.                       ──────│    ║    │────────────────────
  499.                             └────╨────┘    MEMBER
  500.  
  501.         The Association of Shareware Professionals (ASP) wants to make sure
  502.         that the shareware principle works for you. If you are unable to
  503.         resolve a shareware-related problem with an ASP member by contacting
  504.         the member directly, ASP may be able to help. The ASP Ombudsman can
  505.         help you resolve a dispute or problem with an ASP member, but does
  506.         not provide technical support for members' products. Please write
  507.         to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send
  508.         a Compuserve message via Email to ASP Ombudsman 70007,3536.
  509.             The OMB may also be contacted by sending a FAX to the
  510.         ASP FAX number: (616)-788-2765. In communication with the OMB,
  511.         please include a telephone number and/or FAX number if available.
  512.  
  513.     PROGRAM KEYS
  514.  
  515.         CURSOR MOVEMENT
  516.  
  517.             Arrow Keys           Cursor Movement
  518.             Ctrl-Left Arrow      Word Left
  519.             Ctrl-Right Arrow     Word Right
  520.             Home                 Beginning of Field
  521.             End                  End of Line/Field
  522.             Ctrl-Home            Beginning of First Field
  523.             Ctrl-End             End of Last Field
  524.             Tab                  Next field
  525.             Shift-Tab            Previous field
  526.  
  527.         INSERTING AND DELETING
  528.  
  529.             Ins                  Toggle Insert Mode
  530.             Del                  Delete Character at Cursor
  531.             Backspace            Delete Character Left
  532.             Ctrl-Backspace       Delete Word Left
  533.             Ctrl-T               Delete Word Right
  534.             Ctrl-U               Delete to End of Field
  535.             Ctrl-Y               Delete to Last Field
  536.  
  537.         OTHER EDITING KEYS
  538.  
  539.             Enter                Process Current Field
  540.             Ctrl-Enter or F10    Process All Fields
  541.             Ctrl-R               Restore Field
  542.             ESC                  Abort Data Entry
  543.  
  544.         SPECIAL KEYS
  545.  
  546.             F1                   Btr Watch Context-Sensitive Help
  547.             Alt+S                Shell to DOS.
  548.             ESC                  Quit Btr Watch
  549.             Alt+F1               Toggle BIOS Screen Writes
  550.  
  551.         LOG VIEWING KEYS
  552.  
  553.         These keys are available while displaying the log file
  554.         with the 'V' View Log File menu option.
  555.  
  556.             P                    Print the log file
  557.             D                    Delete the log file
  558.             H                    Display the log file help screen
  559.             X                    Exit from viewing the log file
  560.             Up Arrow             Scroll the log file up one line
  561.             Down Arrow           Scroll the log file down one line
  562.             Ctrl-Left Arrow      Page left
  563.             Ctrl-Right Arrow     Paqe right
  564.             PgUp                 Display previous screen
  565.             PgDn                 Display next screen
  566.             Home                 Go to the beginning of the log
  567.             End                  Go to the end of the log
  568.